<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 8.2</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="8.1.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="8.3.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P1">Part I. The Language</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#8">Chapter 8. Compilation, Execution, and Errors</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><a name="C-packages"><h2>8.2 &ndash; C Packages</h2></a>

<p>Because it is easy to interface Lua with C,
it is also easy to write packages for Lua in C.
Unlike packages written in Lua, however,
C packages need to be
loaded and linked with an application before use.
In most popular systems, the easiest way to do that is
with a dynamic linking facility.
However, this facility is not part of the ANSI C specification;
that is, there is no portable way to implement it.

<p>Usually, Lua does not include any facility that cannot be
implemented in ANSI C.
However, dynamic linking is different.
We can view it as the mother of all other facilities:
Once we have it,
we can dynamically load any other facility that is not in Lua.
Therefore, in this particular case,
Lua breaks its compatibility rules and
implements a dynamic linking facility for several platforms,
using conditional code.
The standard implementation offers this support for Windows (DLL),
Linux, FreeBSD, Solaris, and some other Unix implementations.
It should not be difficult to extend this facility to other platforms;
check your distribution.
(To check it, run <code>print(loadlib())</code> from the Lua prompt and
see the result.
If it complains about bad arguments,
then you have dynamic linking facility.
Otherwise, the error message indicates
that this facility is not supported or not installed.)

<p>Lua provides all the functionality of dynamic linking in
a single function, called <code>loadlib</code>.
Its has two string arguments:
the complete path of the library
and the name of an initialization function.
So, a typical call to it looks like the next fragment:
<pre>
    local path = "/usr/local/lua/lib/libluasocket.so"
    local f = loadlib(path, "luaopen_socket")
</pre>
The <code>loadlib</code> function loads the given library
and links Lua to it.
However, it does not open the library
(that is, it does not call the initialization function);
instead, it returns the initialization function as a Lua function,
so that we can call it directly from Lua.
If there is any error loading the library or
finding the initialization function,
<code>loadlib</code> returns <B>nil</B> plus an error message.
We can improve our previous fragment so that it checks for
errors and calls the initialization function:
<pre>
    local path = "/usr/local/lua/lib/libluasocket.so"
    -- or path = "C:\\windows\\luasocket.dll"
    local f = assert(loadlib(path, "luaopen_socket"))
    f()  -- actually open the library
</pre>

<p>Typically, we could expect a library distribution to include
a stub file similar to that previous code fragment.
Then, to install the library,
we put the actual binary shared library anywhere,
edit the stub to reflect the real path,
and then add the stub file in a directory in our <code>LUA_PATH</code>.
With this setting,
we can use the regular <code>require</code> function to open the C library.

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="8.3.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

